Add a note to the style guide about abbreviations by sirosen · Pull Request #1844 · python/devguide

sirosen · 2026-06-26T02:03:19Z

Hat tip to @hugovk for this! Not only the issue (#1824), but also his comments preceding it made this easy to write.

This as a draft because it conflicts with #1828, which is already approved and should ideally merge first.
Once that's done, the exact positioning of this content in the page may change.

Open question: should this be converted to be a subsection of "Use simple language" or "Specific words"?

resolves #1824

After the section on specific terms, but before "simple language", add a section that explains that documentation should spell out acronyms, preferring the "<full-spelling> (<acronym>)" format.

resolves python#1824 After the section on specific terms, but before "simple language", add a section that explains that documentation should spell out acronyms, preferring the "<full-spelling> (<acronym>)" format.

read-the-docs-community · 2026-06-26T02:04:27Z

Documentation build overview

📚 CPython devguide | 🛠️ Build #33801481 | 📁 Comparing d0cdf9e against latest (0164145)

🔍 Preview build

28 files changed · + 1 added · ± 26 modified · - 1 deleted

+ Added

include/links/index.html

± Modified

- Deleted

links/index.html

StanFromIreland · 2026-06-26T07:35:11Z

Hi Stephen, this issue was originally specific to :abbr:, but I like your expanded approach. I would however suggest a little move.

We have a section for Sphinx roles, which is where I think the role-specific guidance should go.
Spelling out acronyms can be moved to "Use simple language" (which, as I think about it now, would be better if it was named "Use accessible language," but that's for another day ;-).

sirosen · 2026-06-26T16:59:09Z

Oh, I hadn't even thought to put it in the role usage docs! 🤦
That seems obvious now.

I want to keep some explanation of the rationale. I'll move things as you suggest, and I think the "some assistive technology" note will end up with the roles.

Edit done! LMK if it needs more tuning.

The role is documented in with other sphinx roles. In order for the rst to read easily, one line of non-semantic whitespace was added to a list. The acronym usage note is moved to the end of "Use simple language"

sirosen · 2026-06-26T17:24:15Z

"Use simple language" (which, as I think about it now, would be better if it was named "Use accessible language," but that's for another day ;-).

Maybe... I like "Use simple language". It has two virtues:

It is a simpler word for the idea of "accessibility", more familiar to more readers -- to a large degree they are equivalent here
In the measure that the two words are not equivalent, "simple" is good general advice for writing well

I could probably be convinced, but we can discuss outside of this PR. 😁

StanFromIreland · 2026-06-26T21:48:44Z

As I said, that's for another day ;-) I also have to catch up on the Discord discussion.

Thanks for the changes, it's what I had in mind.

python-cla-bot · 2026-07-24T20:07:21Z

All commit authors signed the Contributor License Agreement.

Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>

Co-authored-by: Stan Ulbrych <stan@python.org>

JelleZijlstra · 2026-07-26T00:00:19Z

 Don't use Latin abbreviations like "e.g." or "i.e." where English words will do,
 such as "for example" or "that is."

+In general, the first time an acronym is used on a page, spell it out.


Ironically nothing in the devguide defines the "HTML" abbreviation which you use in the other part of this PR. And I think that's a good thing: in computing there are some terms that are more widely understood as abbreviations than as the full form, and adding the full form is more likely to distract than to help readers. HTML is one of those terms. Other examples off the top of my head are UTF-8, PNG, SVG, SQL.

Yeah, sometimes an acronym becomes a term or word in its own right.
The guidance should be read as flexible in this respect.

We added the "In general" to try to succinctly cover this. Do you feel it needs more explanation? We can try another arrangement if the current text looks too strong.

The current text will likely lead people to comment that you need to say "Hyper-Text Markup Language". I'd suggest wording like "Commonly understood acronyms such as HTML or UTF-8 do not need to be expanded."

I tried a few different "spellings" of the idea, and ended up with almost exactly this suggested text.

(Sorry, I broke the typical rules and did an amend, as I forgot to put Jelle in as a co-author at first!)

as I forgot to put Jelle in as a co-author at first!)

In that case, in the future please comment for whoever is merging to add it in (we squash anyway), to avoid amends.

Or add an empty commit with the co-author, or don't worry about it :)

I'll use an empty commit if it comes up again! That way, it's automatically included in the squash and nobody has to do anything extra.

I strive for perfection, including in my citations. Clearly I need to take the no-force-pushes rule into account more strongly! 😅

Co-authored-by: Jelle Zijlstra <906600+JelleZijlstra@users.noreply.github.com>

StanFromIreland

A couple final nits, otherwise looks great.

Additionally, can you fix these, please:

$ gg ":abbr:"
developer-workflow/development-cycle.rst:to the :abbr:`VCS (version control system)`.
developer-workflow/stdlib.rst:tracker and :abbr:`VCS (version control system)`.
developer-workflow/stdlib.rst:by following the :abbr:`PEP (Python Enhancement Proposal)` process.
development-tools/clinic/index.rst:The Argument Clinic :abbr:`CLI (Command-Line Interface)` is typically used to
getting-started/pull-request-lifecycle.rst::abbr:`VCS (version control system)` to be released
getting-started/setup-building.rst:     Contains the :abbr:`PEG (Parser Expression Grammar)` grammar file for
testing/coverage.rst:to the language and :abbr:`stdlib (standard library)` are accompanied by

With those, LGTM :-)

StanFromIreland · 2026-07-28T17:50:30Z

 interpreted text roles of the form ``:rolename:`content```
 to insert semantic markup in documents.

 In the CPython documentation, there are a couple common cases


Suggested change

In the CPython documentation, there are a few common cases

We're now at three :-)

Hmm, that suggestion seems broken, for clarity: "couple" -> "few"

I think I'll do a normal commit with this + the :abbr: fixes + the fix below, so I'll try not to think about what that weird rendering in GitHub means.

StanFromIreland · 2026-07-28T17:51:19Z

 Don't use Latin abbreviations like "e.g." or "i.e." where English words will do,
 such as "for example" or "that is."

+In general, the first time an acronym is used on a page, spell it out.


Can we also add "abbreviation" here please.

Add a note to the style guide about abbreviations

5e900e3

resolves python#1824 After the section on specific terms, but before "simple language", add a section that explains that documentation should spell out acronyms, preferring the "<full-spelling> (<acronym>)" format.

Split :abbr: vs "acronym howto" docs go

3b5d5b5

The role is documented in with other sphinx roles. In order for the rst to read easily, one line of non-semantic whitespace was added to a list. The acronym usage note is moved to the end of "Use simple language"

Merge branch 'main' into add-abbreviations-to-style-guide

7555c40

sirosen marked this pull request as ready for review July 24, 2026 20:07

hugovk reviewed Jul 24, 2026

View reviewed changes

Comment thread documentation/style-guide.rst Outdated

Add "In general, ..." to soften acronym note

d531625

Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>

hugovk approved these changes Jul 24, 2026

View reviewed changes

StanFromIreland reviewed Jul 25, 2026

View reviewed changes

Comment thread documentation/style-guide.rst Outdated

Update documentation/style-guide.rst

0cf8618

Co-authored-by: Stan Ulbrych <stan@python.org>

JelleZijlstra reviewed Jul 26, 2026

View reviewed changes

Add a small note on acronyms not to expand

d0cdf9e

Co-authored-by: Jelle Zijlstra <906600+JelleZijlstra@users.noreply.github.com>

sirosen force-pushed the add-abbreviations-to-style-guide branch from a82602e to d0cdf9e Compare July 28, 2026 16:07

StanFromIreland reviewed Jul 28, 2026

View reviewed changes

Uh oh!

Uh oh!

Conversation

sirosen commented Jun 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

read-the-docs-community Bot commented Jun 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Documentation build overview

Uh oh!

StanFromIreland commented Jun 26, 2026

Uh oh!

sirosen commented Jun 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

sirosen commented Jun 26, 2026

Uh oh!

StanFromIreland commented Jun 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

python-cla-bot Bot commented Jul 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sirosen Jul 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

StanFromIreland Jul 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

StanFromIreland left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

sirosen commented Jun 26, 2026 •

edited

Loading

read-the-docs-community Bot commented Jun 26, 2026 •

edited

Loading

sirosen commented Jun 26, 2026 •

edited

Loading

StanFromIreland commented Jun 26, 2026 •

edited

Loading

python-cla-bot Bot commented Jul 24, 2026 •

edited

Loading

sirosen Jul 28, 2026 •

edited

Loading

StanFromIreland Jul 28, 2026 •

edited

Loading